[DX-1285] Implement `get-message` to retrieve latest version by serial by sacOO7 · Pull Request #385 · ably/ably-cli

sacOO7 · 2026-05-07T12:23:06Z

Fixes https://ably.atlassian.net/browse/DX-1285
Link to internal discussion -> https://ably-real-time.slack.com/archives/C09M25LCZLP/p1778143546471429
Adds ably channels get-message CHANNEL_NAME MESSAGE_SERIAL — wraps the Ably REST SDK's channel.getMessage() to fetch the latest version of a single message by its serial.
get-message is singular and explicit about operation. kabab-case follows existing conventions, e.g. ably push config set-apns
This also display annotations summary for returned msg-serial, currently there's no way to display annotation summary for given msg-serial.
JSON output mirrors channels history's per-element shape (raw SDK message spread, ISO-normalised timestamp, stringified action) — the right precedent for a one-shot REST query. Human output reuses the shared formatMessagesOutput formatter, so the same record renders identically across get-message, history, and subscribe.

vercel · 2026-05-07T12:23:11Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cli-web-cli	Ready	Preview, Comment	May 12, 2026 2:54pm

Copilot

Pull request overview

Adds a new channels get-message command to the Ably CLI to retrieve the latest version of a mutable message by its serial, aligning JSON and human output formats with existing channel message commands.

Changes:

Introduces ably channels get-message <channel> <serial> implemented via Ably REST channel.getMessage(), with optional --cipher support.
Adds unit tests validating SDK invocation, JSON envelope/shape (including timestamp normalization), human-readable formatting, and error surfacing.
Extends E2E mutable-message test coverage to include get-message behavior (basic retrieval, post-update latest version, human output, and unknown-serial failure).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
`src/commands/channels/get-message.ts`	Implements the new `channels get-message` command, including JSON and human-readable output paths.
`test/unit/commands/channels/get-message.test.ts`	Adds unit coverage for argument/flag handling, output shape/format, and error propagation.
`test/helpers/mock-ably-rest.ts`	Extends the REST channel mock with a `getMessage` method and representative message payload.
`test/e2e/channels/channel-message-ops-e2e.test.ts`	Adds E2E coverage for message retrieval and latest-version semantics after updates.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

claude-code-ably-assistant · 2026-05-07T17:25:05Z

Walkthrough

Adds ably channels get-message <channel> <serial> — a one-shot REST command that wraps channel.getMessage() to fetch the latest version of a mutable message by its serial. The PR also tightens the annotation summary indentation in formatMessagesOutput and sharpens the description of channels annotations get to clarify it returns the raw event stream, not the rolled-up summary.

Changes

Area	Files	Summary
Commands	`src/commands/channels/get-message.ts`	New command: fetches latest message version via REST SDK `getMessage()`; supports `--cipher`, `--json`, `--pretty-json`; normalises timestamp to ISO 8601 and stringifies `action` in JSON output
Commands	`src/commands/channels/annotations/get.ts`	Description updated to clarify this returns paginated annotation events, not the rolled-up summary
Utils	`src/utils/output.ts`	Fixed `formatMessagesOutput`: annotations summary now renders with a `Summary` sub-label and corrected indentation (2→4 spaces for annotation type keys, 4→6 for values)
Tests (unit)	`test/unit/commands/channels/get-message.test.ts`	288-line unit suite covering JSON envelope shape, timestamp normalisation, epoch-zero preservation, action stringification, version/annotations passthrough, human-readable field rendering, and error handling
Tests (e2e)	`test/e2e/channels/channel-message-ops-e2e.test.ts`	4 new E2E cases: basic retrieve, retrieve-after-update (with retry loop for eventual consistency), human-readable output fields, and non-zero exit on unknown serial
Tests (helpers)	`test/helpers/mock-ably-rest.ts`	Adds `getMessage` mock to `MockRestChannel` with a realistic default payload including `version` and `annotations.summary`

Review Notes

Behavioral change in shared formatter: The indentation fix in formatMessagesOutput (output.ts:202–218) affects all commands that render annotations — channels history, channels subscribe, and the new get-message. Reviewers should verify the updated visual hierarchy looks correct and that no snapshot/output tests rely on the old spacing.
message.timestamp == null guard: The timestamp normalisation uses == null (loose equality) to catch both null and undefined while preserving a legitimate 0 epoch timestamp — worth a second look to confirm this is intentional and the test covers it (it does: "epoch-zero" test case).
E2E retry loop: The update-then-get test retries up to 10 times with 1 s delays for eventual consistency. This is sound but adds up to 10 s of potential wait time per run — acceptable given the timeout: 60000 guard.
No new dependencies introduced.
annotations get description change: This is a pure documentation fix but could surprise users who expected summary output from that command — the change makes the distinction explicit.

umair-ably · 2026-05-12T12:29:40Z

+import type { MessageDisplayFields } from "../../utils/output.js";
+
+const MUTABLE_MESSAGES_HINT =
+  "The channel may not have mutableMessages enabled — without this rule, individual messages cannot be retrieved by serial. Please check the same using 'ably apps rules list'. If the 'Mutable Messages' rule is enabled, then make sure to enter correct message serial.";


Suggested change

"The channel may not have mutableMessages enabled — without this rule, individual messages cannot be retrieved by serial. Please check the same using 'ably apps rules list'. If the 'Mutable Messages' rule is enabled, then make sure to enter correct message serial.";

"Ensure the channel has a `mutableMessages` rule enabled (run `ably apps rules list`) and that the message serial is correct.";

umair-ably · 2026-05-12T14:18:43Z

I've pulled this down and tested locally. The error hint is not showing in the expected hint property in both json and non-json output. Instead, it appends it to the error itself which is wrong. Can this be updated so it follows the hint property convention

sacOO7 · 2026-05-12T14:47:58Z

I've pulled this down and tested locally. The error hint is not showing in the expected hint property in both json and non-json output. Instead, it appends it to the error itself which is wrong. Can this be updated so it follows the hint property convention

Fixed at 65d2c0e

…sage

- Stringify `action` in JSON output for predictable typing across commands (matches `channels subscribe`'s normalisation; our trace payload and human display already do this). - Use a nullish check on `timestamp` so a legitimate epoch-zero value is preserved as `1970-01-01T00:00:00.000Z` instead of being dropped to `undefined`. (Note: same pattern exists in `channels history`; fixing there is out of scope for this PR.) - Update the in-code comment to drop the inaccurate "strict superset of subscribe" claim — JSON shape mirrors `channels history`'s raw SDK spread, which is the right precedent for one-shot REST queries. - Add unit tests for both the epoch-zero timestamp path and the `action` stringification. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…tions#get

…ailure

…to fail method, accordingly recording error for the same

sacOO7 requested a review from Copilot May 7, 2026 12:23

Copilot started reviewing on behalf of sacOO7 May 7, 2026 12:24 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

sacOO7 requested a review from Copilot May 7, 2026 12:33

Copilot started reviewing on behalf of sacOO7 May 7, 2026 12:34 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

Comment thread src/commands/channels/get-message.ts Outdated

Comment thread src/commands/channels/get-message.ts

Comment thread src/commands/channels/get-message.ts

vercel Bot deployed to Preview May 7, 2026 12:49 View deployment

vercel Bot deployed to Preview May 7, 2026 17:22 View deployment

sacOO7 marked this pull request as ready for review May 7, 2026 17:23

sacOO7 requested a review from AndyTWF May 7, 2026 17:39

sacOO7 changed the title ~~[DX-925] Implement get-message to retrieve latest version by serial~~ [DX-1285] Implement get-message to retrieve latest version by serial May 8, 2026

AndyTWF reviewed May 11, 2026

View reviewed changes

Comment thread src/commands/channels/annotations/get.ts

Comment thread src/commands/channels/get-message.ts

vercel Bot deployed to Preview May 11, 2026 08:45 View deployment

sacOO7 force-pushed the feature/implement-get-message-command branch from b38c16e to b296802 Compare May 11, 2026 08:48

vercel Bot deployed to Preview May 11, 2026 08:48 View deployment

sacOO7 requested a review from umair-ably May 12, 2026 11:30

umair-ably reviewed May 12, 2026

View reviewed changes

vercel Bot deployed to Preview May 12, 2026 12:53 View deployment

sacOO7 force-pushed the feature/implement-get-message-command branch from eea83ba to 4a09e0f Compare May 12, 2026 14:44

vercel Bot deployed to Preview May 12, 2026 14:45 View deployment

sacOO7 and others added 5 commits May 12, 2026 20:23

feat(channels): add get-message to retrieve latest version of a mes…

93f42ef

…sage

Fixed output for channels get-message, updated description for annota…

b82baf4

…tions#get

Addressed review comments related to hint message on message serial f…

97b55e1

…ailure

Updated MUTABLE_MESSAGES_HINT message, added optional hint param …

65d2c0e

…to fail method, accordingly recording error for the same

sacOO7 force-pushed the feature/implement-get-message-command branch from 4a09e0f to 65d2c0e Compare May 12, 2026 14:53

vercel Bot deployed to Preview May 12, 2026 14:54 View deployment

umair-ably approved these changes May 12, 2026

View reviewed changes

umair-ably merged commit 335a18b into main May 12, 2026
15 of 16 checks passed

umair-ably deleted the feature/implement-get-message-command branch May 12, 2026 15:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DX-1285] Implement `get-message` to retrieve latest version by serial#385

[DX-1285] Implement `get-message` to retrieve latest version by serial#385
umair-ably merged 5 commits into
mainfrom
feature/implement-get-message-command

sacOO7 commented May 7, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

claude-code-ably-assistant Bot commented May 7, 2026

Uh oh!

Uh oh!

Uh oh!

umair-ably May 12, 2026

Uh oh!

sacOO7 May 12, 2026 •

edited

Loading

Uh oh!

umair-ably commented May 12, 2026

Uh oh!

sacOO7 commented May 12, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

	"The channel may not have mutableMessages enabled — without this rule, individual messages cannot be retrieved by serial. Please check the same using 'ably apps rules list'. If the 'Mutable Messages' rule is enabled, then make sure to enter correct message serial.";
	"Ensure the channel has a `mutableMessages` rule enabled (run `ably apps rules list`) and that the message serial is correct.";

Conversation

sacOO7 commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

claude-code-ably-assistant Bot commented May 7, 2026

Walkthrough

Changes

Review Notes

Uh oh!

Uh oh!

Uh oh!

umair-ably May 12, 2026

Choose a reason for hiding this comment

Uh oh!

sacOO7 May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

umair-ably commented May 12, 2026

Uh oh!

sacOO7 commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

sacOO7 commented May 7, 2026 •

edited

Loading

vercel Bot commented May 7, 2026 •

edited

Loading

sacOO7 May 12, 2026 •

edited

Loading

sacOO7 commented May 12, 2026 •

edited

Loading